SPACE 1/SPACE - Library 1 - Volume 1.iso/telecomm/515/staladbk/stald_bk.asc

Text File | 1991-10-21 | 106KB | 2,404 lines

                  >>>  ST ALADDIN SCRIPT TUTORIAL <<<
                  """""""""""""""""""""""""""""""""""
                    ~ A T/TalkNET Online Bookette ~

                                   By

                              Fred H. Koch




                     (C)opyright 1991 Fred H. Koch
                          All rights reserved

                   ~ A T/TalkNET ONLINE PUBLICATION ~

                    T/TalkNET OnLine Publishing Co.
                           ATTEN: John Peters
                         5102 Galley Rd. 115/B
                      Colorado Springs, CO. 80915






WHY ST ALADDIN?   Well, I started using Aladdin back in March, and life
"""""""""""""""   has never been the same.  ST Aladdin is by far the most
useful program I've ever had.  My Atari practically never leaves the
program.

    My Aladdin use has changed much in the last three months.  The first
month was spent trying the program out.  I spent most of my time here in
the ST Aladdin RT.  I continued my old habits, and frequented the ST RT,
as well.  I made about 100 calls and was online about 8 hours.  My GEnie
costs were about the same as always.

    The second month, I became braver.  I started exploring computer RT's
and my inexperience with ST Aladdin led to many expensive connections
downloading thousands of unwanted messages.  I still made about 100
calls, and was online about 12 hours.  My bill was $60 compared to the
usual $15, though.

    The third month, I discovered the Star*Basic services, i.e. free
stuff.  I had never been able to use these public discussions because
exploration was so difficult manually.  I've found these area extremely
interesting, and now rarely go to the computer RT's at all.  Heck, my
Atari is always in Aladdin, and that works fine, so there are few
questions that I need resolved.

    My online hours has shot up to 19, but my costs have now gone down to
the $10-$15 range.  At $15/19 hours ($.78/hr), the Aladdin-GEnie combo
is a great deal.

    I just wanted to let you know what a great program you've developed
and how one happy camper is making use of it.
                 (M.MILLS, CAT3, TOP5, MSG:79/M1000)




                            >>> PREFACE <<<
                            """"""""""""""""

ST ALADDIN SCRIPT TUTORIAL   The purpose of the ST Aladdin Script
""""""""""""""""""""""""""   Tutorial is to introduce ST Aladdin users
to scripts.  Scripts not only automate your session on GEnie using ST
Aladdin, but also add capabilities which are not directly provided in
ST Aladdin.  These tutorials were originally published in GEnie Lamp,
the Atari ST online magazine of GEnie.  They are based on ST Aladdin
version 1.2a and the GEnie menu structure of March 1991.  The examples
and commands are specific to ST Aladdin and GEnie, but the principles
explained apply to writing scripts for any telecommunications program.
Examples of ST Aladdin scripts can be found on GEnie in the ST Aladdin
RT Library.  Log onto GEnie and type M1000 to enter the ST Aladdin RT.
Search the library for SCRIPT to find the current files.




ACKNOWLEDGMENTS   I wish to say thanks to numerous persons who assisted
"""""""""""""""   in creating the articles which make-up this booklet.
John Peters for developing the idea behind Online Booklets and my wife
Linda for having the patience to allow me the time to produce the
tutorials.  I can't forget all the people on the GEnie ST Aladdin RT who
asked questions and encouraged script development.  Perhaps most of all I
have to thank Gordon and Tim for writing ST Aladdin, without which I would
have remained an infrequent user of GEnie.



                       >>> TABLE OF CONTENTS <<<
                       """""""""""""""""""""""""

 INTRO TO SCRIPTS ........ [PT1]        PROBLEMS WITH SCRIPTS ... [PT2]

 TEXT AND VARIABLES ...... [PT3]        CONDITIONAL BRANCHES .... [PT4]

 UNCONDITIONAL BRANCHES .. [PT5]        FILE COMMANDS ........... [PT6]

 OTHER COMMANDS .......... [PT7]        INTRO, INTERRUPTED ...... [PT8]

 COMMAND SUMMARY ......... [PT9]        COMMAND INDEX .......... [PT10]


[IDX]
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
READING A BOOKETTE   T/TalkNET has incorporated a unique indexing system
""""""""""""""""""   to help make reading the magazine easier.  To
utilize this system, load this Bookette into any ASCII word processor or
text editor.  In the index you will find the following example:

                     PROBLEMS WITH SCRIPTS ... [PT2]

     To read this chapter, set your find or search command to [PT2].  If
you want to scan all of the articles, search for [EOA].  [EOF] will take
you to the last page, whereas [IDX] will bring you back to the index.
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""






                   >>> ST ALADDIN SCRIPT TUTORIAL <<<
                   """"""""""""""""""""""""""""""""""
                             ~ Fred H. Koch ~




CHAPTER 1
"""""""""
    [PT1]

                        >>> INTRO TO SCRIPTS <<<
                        """"""""""""""""""""""""

     There is much talk about scripts among the telecommunications crowd.
Scripts can make telecommunicating much easier, reducing or even
eliminating many manual steps.  This article and those which follow will
discuss how to create scripts, specifically for ST Aladdin, but many of
the items discussed will apply to creating scripts for any terminal
program.

    A script is a list of instructions which the terminal program can use
to perform the desired actions, with little or no operator intervention.
Each terminal program which supports scripts does so in its own unique
fashion.  Many of the capabilities are similar, but exactly how each is
implemented and the exact format is different.

    Even if you have no programming experience, simple scripts can be
created to make your telecommunicating easier and faster.  Any action
which you perform frequently, using the same steps, is a candidate for
using a script.  Most scripts allow using variables so the same steps can
be performed with different inputs, reducing the repetitiveness, and
increasing the usefulness.

    Once a script is created, anyone who has the same terminal program can
use the script by knowing what inputs the script needs.  They don't have
to understand how the script works or know the commands the script uses.
This allows people to perform operations faster and easier without having
to actually learn or remember the process themselves.

    Now for how to actually write a script.  The first step is to perform
the desired operation manually, exactly the way you want the script to do
it each time, and capture the operation as it is done.  This captured list
of actions is the basis for your entire script, so it must be done
correctly, if not your script will not do what you want. This may take
some practice to insure the actions are recorded the way you really want
things to happen.  You can use a capture which includes mistakes and extra
steps, but this makes script writing much more difficult and tends to
introduce errors in the final product.

    Once the capture is made, it is best to print the file so easy
reference can be made to each step.  Since a script is nothing more than a
series of instructions, the capture will provide the sequence of steps for
the script.  The printout also allows reference to the exact key words
used by the called system when requesting information.  These key words
are used by the script to know when to pass the next piece of information.
The script works by recognizing a request from the called system (or host)
and providing the proper response for that request.

    All scripts contain two key types of actions.  The first is
recognizing the host system request for input (often called a prompt), and
the second is sending the proper response.  Recognizing the prompt is
nothing more than matching characters.  The script waits until the proper
sequence of characters is received before proceeding.  An ST Aladdin
example is:

    WAITFOR "skip?"

    The script will not proceed until that exact sequence of characters is
received.  Exact sequence is important.  Since characters are received one
at a time, and S is different than s to most scripts, the exact sequence
makes a big difference in getting a script to work properly.  If you do
not tell the script to watch for the correct sequence of characters, it
will patiently wait all day for what you told it to wait for, not knowing
it will never come.  In the above example, if

     WAITFOR "Skip?"

    had been used, the script would never go to the next step, since the
capital Skip will not be received from the called system, only skip.

    Choosing enough characters to allow the script to proceed when it
should, but not too many to allow line noise to confuse the script, is a
delicate balance in some cases.  Line noise is that crackle or pop you
hear when listening to a telephone conversation.  We don't think much
about it, but to a computer, it is significant.  That crackle or pop can
produce an unwanted character in the string of characters coming to your
computer.  In the above example, with line noise, the skip? might look
like this:

    s{kip?

    when coming to your computer.  The script is looking for the exact
sequence of characters you entered, so it will not recognize s{kip? as the
proper prompt, and will not proceed.  This is where the balance between
enough characters to uniquely define the prompt and as few as possible to
reduce the impact of line noise, comes in.  If the computer receives:

    is this the time to skip?

    as part of a message it would dutifully proceed with the next
instruction after receiving the skip? from the message.  It doesn't know
the skip? it received is part of a message and not a system prompt.

    Choosing the proper words or phrases can be one of the more
frustrating parts of trying to write a working script.  It generally isn't
a problem, but can be if a few precautions to provide unique matches are
not taken.

    Most BBS systems realize the problems which can occur if the system
prompts are not unique, so they try to make them distinct from other
naturally occurring phrases.  As long as you take the time to recognize
what it is that makes the prompt unique there will be no problem.  When in
doubt, make the script phrase to be looked for match the whole prompt.
This will reduce the risk of the script proceeding when it shouldn't.
Whenever a script proceeds before you intended, an early match is the most
probable reason.  Make the required character match more descriptive to
correct the problem.  If line noise is a problem, the phrase can be
shortened later, after you determine the script works.

    Fortunately, GEnie uses the same prompt for most of its requests.
Aladdin uses this unique request format to simplify its script writing
with the command WAITFORPROMPT.  This command will recognize any GEnie
standard prompt and proceed with the script sequence.

    The next step following recognizing the proper prompt is providing the
proper response to the prompt.  This is much easier since you have already
done it once manually.  There is always a command to tell the script to
send a sequence of one or more characters, in ST Aladdin it is SEND or
SENDLINE.  SEND will send the desired character(s) with no carriage
return, where SENDLINE will provide the carriage return and line feed
after the character(s) is sent.  Following the above example, if the
proper response is Y, the script line for ST Aladdin would be:

    SENDLINE "Y"

    This would cause the terminal program to send the character Y after
receiving the skip? prompt, instructing the called system to proceed.
    Line noise can still be a problem when sending the response.  If
the called system is expecting Y or YES and line noise causes it to
receive

    {Y

    the system will probably not proceed.  It may provide an error message
such as GEnie's:

    Unrecognized command [{Y]

    or may just repeat its previous prompt.  Since the called system does
not generally evaluate the response until a carriage return is received,
it includes any line noise characters in the response.  Line noise in the
prompt or the response can cause a problem with the script proceeding.
Ways to deal with line noise will be covered in a later article.

    With only these two commands, some very useful scripts can be created.
One of the first scripts I created uses only these two commands, and
allows automated log on to the local bulletin boards I frequent.

    Before quitting this article, let me give an example of a simple
script creation process using only the above two commands.  The script
will be very simple and of limited use, since the same actions are already
contained within ST Aladdin, but it will serve to demonstrate the process.

    I begin the capture with Aladdin and select log onto ST Aladdin BB.
Next I perform all the actions manually I want the script to be able to
perform.  The capture shown below is abbreviated to contain only the
significant portions for space reasons.  My comments will be in {} braces.

{preceded by the initial GEnie log on sequence accomplished by Aladdin.}

Category  1 Welcome to the ST Aladdin BB
1 ?REA ALL NEW CAT=1-99 NOR
{1 ? is the prompt provided by GEnie}
{I enter REA ALL NEW CAT=1-99 NOR}
{which means read all new messages in categories 1-99 with no reply}
{GEnie responds with the new messages}
************
Topic 10        Fri Feb 01, 1991
R.BAUKNECHT [RICK]           at 20:48 CST
Sub: WHAT IS ALADDIN ST -VS- ALADDIN PC ?
WHAT IS THE DIFFERANCE BETWEEN ALADDIN PC AND ALADDIN ST?*S
4 message(s) total.
************
------------
Category 1,  Topic 10
Message 4         Sun Feb 03, 1991
R.BAUKNECHT [RICK]           at 23:13 CST
YOU`RE RIGHT IT IS SIMPLE,THANKS FOR THE HELP!   I GUESS I`LL MOVE ON
DOWN TO ALADDIN PC. RICK
------------
{other messages follow}
1 ?BYE
{after the last message GEnie responds with the prompt again}
{I enter BYE to end the GEnie session}


    After ending the capture, I have all the information needed to create
a script to check for new messages any time I want.  Admittedly this is
very simple but we have to walk before running.  To create the script I
look at each system prompt provided and the response I want to make.

    We will keep it simple and log on manually each time.  All the script
has to do is provide the proper responses to retrieve the new messages.
The first thing we need to do is provide GEnie the proper command.  We do
not need to wait for the prompt since it is already there before we begin
the script.  Knowing where to start the script is not always obvious, more
on that in a later article.

    ST Aladdin has some requirements for all scripts, namely telling it
where the script begins and ends using the SCRIPT and ENDSCRIPT commands.
Each script must also have a unique number from 3 to 9.  A title line of
up to 30 characters can be added which is displayed when listing the saved
scripts.  Providing for these requirements, the first script command is:


SCRIPT 3 Read New messages

    To actually send the desired command to GEnie the next command is:

SENDLINE "REA ALL NEW CAT=1-99 NOR"

    GEnie will respond with all the new messages.  We want the script to
proceed after all new messages are displayed.  We could use the WAITFOR "1
?" command, but if a message contained 1 ? the script would proceed before
we wanted.  To reduce the problem of message content confusing the script,
we use the unique prompt command in ST Aladdin's script language.  The
next command is then:

WAITFORPROMPT

    The script will not proceed until GEnie sends the unique prompt. After
receiving the prompt, in this case 1 ? the script must log off. We could
just use SENDLINE "BYE", but ST Aladdin provides a special command to log
off called LOG OFF so we will use it.

LOG OFF

    To finish the script properly we have to tell Aladdin the script is
done with the command:

ENDSCRIPT

    That is it.  The complete script without the comments is:

SCRIPT 3 Read New messages
SENDLINE "REA ALL NEW CAT=1-99 NOR"
WAITFORPROMPT
LOG OFF
ENDSCRIPT

    Of course there are lots of other things we would like the script to
do.  Perhaps log onto GEnie, open and close the capture for us and allow
reading more than just the new messages.  These are easily accomplished,
but that will be saved for a future article.

    To get this script into Aladdin we have to select Edit User Scripts
from the File menu and type the above five lines into the editor. Aladdin
does not care if the commands are upper or lower case, but the case of the
characters to be matched is very significant.  Pressing ESC or clicking on
the window close box will save the script.  The number assigned to the
script is not critical, as long as it is the next number in the script
list, so if there were already 4 scripts this one could be number 5.
Aladdin does not seem to like scripts being out of sequence.

    To use the script we need to start the capture, log onto a GEnie
bulletin board with Aladdin, select Do User Script from the Terminal menu,
click on Read New messages and click on OK.  If we made no typing mistakes
in the script, Aladdin will send the read new messages command, GEnie will
respond with the new messages, then Aladdin will log off. Since nothing in
this script is unique to the ST Aladdin BB it could be used with any
bulletin board on GEnie.  With some minor changes, we could just select
the proper script and Aladdin would do the rest for us.  In fact that is
exactly what happens when using AutoPass 1 or 2 in Aladdin.  In a future
article we will change the script to make it really useful, not just a
duplication of what Aladdin can already do.




CHAPTER 2
"""""""""
    [PT2]
                     >>> PROBLEMS WITH SCRIPTS <<<
                     """""""""""""""""""""""""""""

    Last time I gave a quick intro to what scripts are, why some people
like them, looked at two commands always used in a script, and explained
the basics of writing a script.  This week we will take a look at why
scripts don't always work the way we planned, some of the more common
problems and most importantly, how to fix those problems.

    First let me reemphasize script writing is not difficult, it does
require close attention to detail, but it is not difficult.  Not paying
close enough attention to detail is one of the most common problems with
writing scripts.

    Aladdin provides some checks on the wording or syntax of a script. If
it encounters a word it doesn't understand as a command it will display
a SCRIPT ERROR: message, and the script will abort.  Most times it is just
a spelling error in one of the commands or forgetting to provide the item
the command needs to work with (called the argument).  The message
displays the line that caused the problem with a hint to what the problem
was, if Aladdin knows.  To correct it, examine each line to see that it
matches the correct command and provides the argument the command needs.
Aladdin commands can be upper or lower case.

    As I mentioned last time, a script is just a list of instructions some
of which wait for a prompt and others that provide the information the
prompt is requesting.  If the script is waiting for the wrong prompt, it
won't proceed when you expect it to.  Little things count a lot when
waiting for a prompt.  The script matches characters one at a time.  If it
is expecting Skip and receives skip, it won't proceed. This includes
leading and trailing spaces if they are included in the script.

    When trying to run a newly created script, it is always a good idea to
capture the session just in case problems occur.  If there is a problem
you can log off and check the capture to see where the problem occurred
and what the discrepancy was.  Two frequent problems are the script not
proceeding or proceeding too soon.

    If the script will not proceed when expected, look at the exact prompt
- there has to be a mismatch between the string the script is looking for
and the one sent by the system.  Solving this problem requires close
examination of the script commands and the captured file. Make sure all
typing is correct, including capitalization and those punctuation marks
which are not easily distinguished, such as a comma and period, semicolon
and colon.  If you can't see what the difference is, try using the search
function of your text editor.  Type in the string you told the script to
look for and see if the search stops at the prompt in the capture and at
the string in the script.  Be sure to use the case sensitive search so
capital letters are distinguished.  If the search doesn't find the prompt
but does find your script command, there is a mismatch which must be
fixed.  Don't forget to check the spaces in the string, including leading
or trailing, they are significant when used in the script WAITFOR string.

    One of the easiest ways to reduce typing errors when creating a new
script is to load the capture into your text editor.  Once the capture
is available, you can either edit the capture, deleting the unimportant
lines and adding the proper WAITFOR and SEND commands before the
appropriate text, or cut and paste the information into the script.

    If the script proceeds too early, then the string the script was
waiting for matched something else besides the prompt.  You need to make
the string more descriptive.  Most often this means looking for some
unique character sequence that appears only in the prompt.  Again using
the search feature of your text editor is a good check.  Start at the
point in the capture where the script last worked correctly and search for
the string you entered in the script.  The search should find the string
before getting to the system prompt, in which case you need to find some
way to change the script string to make it unique.  The search feature is
a good way to test the new string to make sure it isn't found too early.
Usually adding the punctuation which ends the prompt will do the trick.
Remember, the script is checking all characters received for a match, it
can't distinguish one string from another, if it matches, the script will
proceed.

    The Aladdin WAITFORPROMPT command can be a big help in preventing
confusion about when the script should proceed.  It not only looks for
the prompt character set in the Aladdin preferences, but also checks
that no other characters follow the prompt.  This insures the host is
waiting for a response before the script continues.  If the information
the script needs to send is requested at a system prompt use the
WAITFORPROMPT command, it can prevent many problems.

    Just so you don't get confused when trying to capture an Aladdin
script session.  Aladdin can only have one capture open at a time.  If you
have a capture started and the script being run also opens a capture, the
first capture will be closed and not reopened, even when the script
capture is closed.  To get around this you will need to either open your
capture again when the script capture is done, or disable the script
capture during the testing phase.  I will discuss the ST Aladdin capture
command in another article.

    I discussed line noise last time, but only briefly touched on
remedies.  Line noise can't always be prevented, and if present is a sure
source of problems for scripts.  Line noise causes extra characters to be
received from the host system which causes the script to not recognize the
prompt.  The script will keep looking for the correct match, but the host
system will only send the prompt once and wait for a response before
proceeding.  Thus the script is waiting for a string which was already
sent and the host is waiting for a response which the script will not
send, and they wait and wait until a time out occurs.

    Several things can be done to help the line noise problem.  If there
is only occasional line noise, making the prompts and responses as short
as possible will reduce the chance of the stray line noise characters
hitting during these critical transmission times.  If a bad response is
sent, there is little to be done except abort the script with ESC and
start over.

    ST Aladdin provides some help with missed prompts.  The FIX function
will try to rematch GEnie and Aladdin.  FIX (F4) will tell the Aladdin
script to go ahead with the next step.  If a single prompt was missed due
to line noise, this should put things back in sync.  I have never had to
use it, but it is the only way to try to fix a script and host mismatch
without logging off and starting over.

    If line noise is present on some calls and not others, try logging off
and calling back when you have a noisy connection.  Each connection can be
over a different set of lines.  The next hook up could be much better.
This is especially true when making a call to another city as with most
GEnie connections.  I heard a telephone representative explain that with
computer switching and automatic routing, a call from Colorado Springs to
Denver (45 miles for those unfamiliar with Colorado) could go through
California, Washington state and North Dakota before getting routed to
Denver.  Now you can see why some calls are noisier than others.

    If line noise is really bad, changing to a lower baud rate will
generally reduce or eliminate it.  The faster the transmissions the
cleaner the lines need to be.  If line noise is bad, slowing down the baud
rate will sometimes even save time, since less retries are needed.

    Another area of possible problem is where to start a script.  The
starting point depends on when the script will be activated.  In the
example last time, the script was activated after we navigated to the
proper bulletin board and the host was ready to receive the next request.
In this case the script started with a command to send our request.  This
is the case for most Aladdin scripts, because Aladdin takes care of the
initial connection to GEnie.  That is why it is even more important to
start a script at the proper place with Aladdin than some other script
languages.  If you start at the wrong place, the script and GEnie will be
out of sync with no way to get matched up again.  The convenience of
having the same prompt for most requests is also a hazard if you get
started wrong.  There is no easy way for the script to tell it isn't where
it should be.  Referencing the capture used to create the script is of
great help in determining the starting point.

    To fully automate a script, the first command which interacts with
GEnie is usually the LOG ONTO command.  This command tells Aladdin to log
on to the specified area of GEnie.  It will use the Aladdin settings to
call GEnie, provide your user ID and password, then move to the specified
page and menu selection, if provided.  A quirk of the LOG ONTO command is
it does not return control to the next script command until after the
GEnie system prompt is received.  Consequently the next command after the
LOG ONTO command is always going to be a SEND or SENDLINE command.  GEnie
is waiting for a response and the script must provide it.

    The LOG ON command is available too, but it only logs onto GEnie and
leaves you at the opening page prompt.  Most times the script needs to be
on some other page to accomplish its task, so it saves time to use the LOG
ONTO command instead.

    Now lets use the LOG ONTO command to make the read new messages script
from the last article a little more useful.

    Instead of having to log onto GEnie manually as we did previously, we
can use the LOG ONTO command to instruct the script to take us to the
bulletin board where we want to read messages.

    LOG ONTO "1000;1"

tells Aladdin to instruct GEnie to immediately go to page 1000 menu item 1
at the completion of the log on sequence.  Page 1000 is the ST Aladdin
page.

    Because the LOG ONTO command stops after GEnie has already sent the
system prompt for page 1000 menu item 1, the script must continue with the
desired response to that prompt.  In the read new messages case the script
proceeds with the command to read new messages.  Since this is where the
previous script started the rest remains the same.  To add the new command
to the script, just insert the command after the SCRIPT 3 command.  The
modified script is shown below.

SCRIPT 3 Read New messages
LOG ONTO "1000;1"
SENDLINE "REA ALL NEW CAT=1-99 NOR"
WAITFORPROMPT
LOG OFF
ENDSCRIPT

    If we want to look at the messages on another bulletin board we
need to edit the page number in the LOG ONTO command.  That is a pain,
but using a variable for the page number would allow us to enter the
page number without physically editing the script each time.  Variables
can make scripts very flexible and much more useful.  How Aladdin
scripts use variables will be the topic of the next article.




CHAPTER 3
"""""""""
    [PT3]

                       >>> TEXT AND VARIABLES <<<
                       """"""""""""""""""""""""""

     Now that we have covered how to create simple scripts, it is time to
start looking at the more powerful features of scripts.  One of the most
powerful features is the use of variables.  By using variables within a
script we can use the same script to accomplish the same operation in many
different areas of GEnie.  No longer will the script need to be modified
for each area to be accessed.

     Variables in a script are the same as variables in math.  They are
characters which represent other characters and can be acted upon just as
if the represented characters had been used in the first place.  The
difference from math is that script variables can represent letters as
well as numbers.

     The advantage of using variables in a script is the script can be
designed to request certain values when started and then use those values
as the script executes.  These values can be almost anything, but the most
common uses are for RT page numbers, file names or numbers, menu
selections, and other choices normally selected when using GEnie manually.

     If the script is going to request the input of these values then
there must be some way for the script to print a message on the screen.
This is exactly what the NOTE command is for.  The NOTE command will
display whatever follows it on the screen.  The format is:

    NOTE "one or more characters"

the characters inside the quotes will be displayed on the screen when the
command is reached during script execution.

     The NOTE command can use other characters to mark the string of
characters which is to be displayed.  The other characters are ( ),[ ],
{ }, ` ' or < >.  Which ever one starts the string, the corresponding
character must end the string.  The variety of characters which may be
used allows including one or more of the characters within the string to
be displayed.  For example, if you wanted to quote something to be
displayed on the screen, you could use the [ ] characters to mark the
string to be displayed so the quotes would be displayed.  Such as

    NOTE [Look for the word "help" on the screen.]

     The NOTE command with no text to display will display a blank line or
be the equivalent of pressing RETURN in a text editor.

     Another command which goes along with the NOTE command is the CLEAR
command.  This command will clear the screen.  This is useful when
starting a script to be sure your instructions aren't lost in previous
text displayed on the screen.  The format is:

    CLEAR

     Now back to variables.  ST Aladdin allows 10 user defined variables
represented by the numbers 0 thru 9.  These variables can be set within
the script, or set by entering characters from the keyboard.  The two
commands are SETSTRING and GETSTRING respectively.

     The SETSTRING command will assign the specified characters to the
specified variable.  The format is:

    SETSTRING 1 "This is the string"

After the script executes this line the string variable 1 will be replaced
by the phrase, This is the string, anywhere it is found in the script.

     The GETSTRING command will assign the characters entered from the
keyboard into the specified variable when the RETURN key is pressed. The
format is:

    GETSTRING 1

After the script executes this line the script will wait for the RETURN
key to be pressed.  When RETURN is pressed the script will assign the
characters entered before RETURN was pressed to the variable 1.  The
GETSTRING command is limited to a single line of up to 79 characters. If
the ESC key is pressed before the RETURN key, the GETSTRING command will
be aborted and the variable will be cleared.

     When using the GETSTRING command it is very beneficial if there is a
NOTE command immediately before the GETSTRING command stating what
information the script needs.

     The variables created using the SETSTRING and GETSTRING commands can
be used in the script the same way any other string is used.  A % sign is
placed in front of the variable number to identify it as a variable and
not a number.  An example is:

    SETSTRING 1 "This is the string"
    NOTE "%1"

would display on the screen:

    This is the string

     Variables can be combined to form a single string by placing them
together just as letters and words can be placed together.  An example is:

    SETSTRING 1 "This is "
    SETSTRING 2 "the string"
    NOTE "%1"
    NOTE "%2"
    NOTE "%1%2"

would display on the screen:

    This is
    the string
    This is the string

     Variables cannot be broken back down into pieces once created. That
means you can't take a sting which is "This is the string" and only use
the "This is" part of it.  They can be put together but not pulled apart.

     Now we will use the NOTE and GETSTRING commands to make the Read new
messages more useful.  With these commands we can make the script much
more useful and even make it into something ST Aladdin doesn't do for us.

     By the script requesting which bulletin board to check messages on
the script will no longer need to be modified for each board to check. By
requesting a date to check messages after, the script will no longer be
limited to checking only new messages.  We could even have the script
request which categories to check so only selected categories would be
checked, but that will be left for a personal exercise if desired.

     A command which should be used any time the GETSTRING command is
going to be used for entering a GEnie command is the SUCCESS command.  I
will cover it in detail in the next article, but for now it tells the
script if the string was entered successfully or if the ESC key was
pressed to abort the entry.  Without using the SUCCESS command the ESC key
could be pressed and the script would try to proceed with an invalid
variable value.  The results are usually GEnie not knowing what to do and
the script staying online until ST Aladdin times out.

    The ECHO command determines if the script will display commands as
they are executed.  The default is ECHO ON which will display commands as
executed.  This is good when trying to see if a script is working as
planned, but tends to mess up the display for routine operations.  It is
best to turn ECHO OFF once you are sure the script works.

     Adding a CLEAR and some NOTE and GETSTRING commands the new script
looks like this:

SCRIPT 3 Read Messages
ECHO OFF
CLEAR
NOTE
NOTE "This script will retrieve messages from a GEnie bulletin board"
NOTE "starting at the specified date. Messages from all categories not"
NOTE "permanently ignored will be retrieved."
NOTE
NOTE "Be sure to start a capture file before running this script."
NOTE
NOTE "The ST Aladdin bulletin board is on page 1000."
NOTE "The Atari ST RT bulletin board is on page 475."
NOTE "Enter the page number of the bulletin board to retrieve
      messages."
NOTE "Press ESC at any time to abort the script."
GETSTRING 1
IF SUCCESS
NOTE "Enter the date to start reading messages as YYMMDD.(Year
      Month Day)"
GETSTRING 2
IF SUCCESS
LOG ONTO "%1;1"
SENDLINE "REA ALL ALL CAT=1-1000 DATE>%2 NOR"
WAITFORPROMPT
LOG OFF
ENDIF
ENDIF
ENDSCRIPT

     Now the script will not need to be modified to access any bulletin
board on GEnie.  There are still some improvements to be made though. It
would be nice if the script would open and close the capture for us, or
even remember the page number of our favorite bulletin boards. These can
be easily accomplished with a few more commands which we will look at next
time, one of which is the IF command used above in IF SUCCESS.




CHAPTER 4
"""""""""
    [PT4]


                      >>> CONDITIONAL BRANCHES <<<
                      """"""""""""""""""""""""""""

     Another major power feature of scripts is being able to skip certain
portions of a script when it doesn't apply to our current desired
actions.  This capability is called branching and allows a single script
to do many different functions.

     Branching in scripts is very similar to branching in a program and
can be used in many of the same ways.  Don't let this scare you if you're
not a programmer.  This will be painless, I assure you, and not very hard
at all.  The branches used in ST Aladdin scripts are very simple and easy
to understand.

     The last script we completed allowed entry of the page number for
the GEnie bulletin board where we wanted to read messages.  If we use
branches, instead of having to enter the page number, we could enter a
number from a menu selection and allow the program to enter the proper
page number for us.  Lets look at how this can be done.

     There are two basic types of script branches.  Conditional and
unconditional.  Just as the name implies, conditional branches will be
taken if the conditions are right and will not be taken if they are
wrong.  Unconditional branches will be taken every time they are
encountered.

     Aladdin implements the conditional branch with the IF condition
command.  Whenever this statement is encountered in a script, the
condition is checked.  If it is met (true) the instructions which follow
the condition are completed.  If it is not met (false) the instructions
are skipped.  An example:


    IF STRING 1 IS "F.KOCH"
       NOTE "Hello Fred."
    ENDIF

     This is a very simple example.  When the script encounters this
conditional branch it checks the contents of variable 1 and makes the
comparison.  If script variable 1 contains the value F.KOCH the script
will print Hello Fred. on the screen.  If variable 1 contains something
else, the print Hello Fred. step is skipped.

     ST Aladdin allows nine different checks in the conditional branch.
This week I will only mention the three I use most.  With these three you
can create many powerful scripts.

     The ST Aladdin conditional branch format is:

     IF condition
       instruction 1
       instruction 2
       etc...
     ELSE
       instruction 8
       instruction 9
       etc...
     ENDIF

     The instructions between the IF condition and the ELSE will be
performed if the condition is met (true).  The instructions between the
ELSE and the ENDIF will be performed if the condition is not met (false).
The ENDIF marks the end of the conditional branch.  The ELSE part is
optional and if not included, the step following the ENDIF will be
completed immediately if the condition is not met.

     The ELSE is especially helpful if there are only two choices to be
made.  Using the previous example:

     IF STRING 1 is "F.KOCH"
       NOTE "Hello Fred."
     ELSE
       NOTE "Hello."
     ENDIF

     In this instance the user will always be greeted, even if variable 1
is not what was expected.

     I briefly mentioned the IF SUCCESS condition when talking about
variables in a previous script article.  IF SUCCESS determines if the
previous action was successful or not.  If the instruction executed right
before the IF SUCCESS branch was successful (true), the branch will be
taken, if it was unsuccessful (false), it will be skipped.

     The success conditions which may be checked are:

    CAPTURE        - was the capture started?
    ENDCAPTURE     - was the capture ended?
    ERASEFILE      - was the file erased?
    GETSTRING      - was a string entered?
    LOG ON         - was log on successful?
    LOG ONTO       - was the log onto successful?
    SNAPSHOT       - was the screen snapshot accomplished?
    WAITFOR        - was the specified string received?
    WAITFORPROMPT  - was the prompt received?
    WAITUNTIL      - was the specified time reached?
    XMODEM         - was the XMODEM operation completed?

     There is a special case, the SUCCESS command.  This is different
from the IF SUCCESS branch command.  The SUCCESS command will set the
condition of SUCCESS to force a branch or prohibit a branch, when the IF
SUCCESS branch is reached.  The SUCCESS command is either SUCCESS TRUE
which will force a branch or SUCCESS FALSE which will prohibit a branch.

     I mention all the script commands which could affect the IF SUCCESS
command for completeness, but some of them may never be used in your
scripts.  An example of the IF SUCCESS branch is shown with the GETSTRING
command in the script at the end of this article.

     The next branch condition to examine is the STRING condition.  This
command compares a script variable with the specified string and takes
the form:

     IF STRING digit verb string
        instruction 1
        etc...
     ELSE
        instruction 8
        etc...
     ENDIF

where:

     digit is 0 to 9 representing the ten possible script variables.

     verb is either IS or HAS.

       IS requires the variable match exactly, including upper/lower case.

       HAS requires the variable contain the specified string.

     string is the characters to match enclosed by string delimiters.
       (delimiters show where a string starts and stops, ie. " ")

     Examples of IF STRING digit IS were shown above.

     The HAS verb allows checking for a series of characters contained
within another string.  This is good if you aren't sure what else might
be included in a variable entry, but you know a specific group of
characters must be included.  An example is:

    IF STRING 1 HAS "F.KOCH"
       NOTE "Welcome Fred."
    ELSE
       NOTE "Welcome."
    ENDIF

     In this case if string 1 contained "My address is F.KOCH." there
would be a match.  No match would occur if the IS verb was used.

     IF CURRENTLINEHAS is the last condition I will discuss in this
article.  This command is used to determine if the current line being
received at the time the command is encountered contains the specified
characters.  The current line is ended by a carriage return.
The command has the form:

     IF CURRENTLINEHAS "string"
       instruction 1
       etc...
     ELSE
       instruction 8
       etc...
     ENDIF

     The comparison is case sensitive, like the other string comparisons,
so the string match must be exact.

     This command should work with any string received through the modem,
but I have only had success using it with prompt lines where GEnie waits
for a response from the script before proceeding.  This is partially due
to the fact if GEnie is not waiting for a response, it doesn't matter
what the script does, it won't change what GEnie is doing.  The other
reason is it is difficult to match the script response timing with GEnie
execution if GEnie is not waiting for the response.  (There are some
commands GEnie always responds to like BREAK, but I will exclude them for
now.)

     An example from the ST Aladdin manual is:
     IF CURRENTLINEHAS "Enter #"
       SENDCOMMAND "C"
     ENDIF

     If Aladdin receives a page prompt with the characters Enter #, it
will send the command C to turn off full prompts.

     I need to mention one caution with this command.  The comparison is
made as soon as a line is received, it does not keep checking the input
until the desired string is found.  It checks the first line received and
then continues.  This means if you want to check several lines for a
specific sequence of characters you will need to repeat the check for
each line until it is found.  If a line was received just prior to the
script encountering this conditional branch, that line is checked.  This
is a good way to determine if the current prompt line contains a
specified string.

     Next time I will discuss the unconditional branches in the ST
Aladdin script language.  Before I end lets see how to use a conditional
statement in the read messages script we have been building.

     A conditional branch can be used to provide the desired RT page
number from a menu selection.  The modified script below shows one method
of accomplishing this.

SCRIPT 3 Read Messages
ECHO OFF                           Don't display script commands
CLEAR                              Clear the screen
NOTE
NOTE "This script will retrieve messages from a GEnie bulletin board"
NOTE "starting at the specified date.  Messages from all categories not"
NOTE "permanently ignored will be retrieved."
NOTE
NOTE "Be sure to start a capture file before running this script."
NOTE
NOTE "       Bulletin boards available"
NOTE
NOTE "       1  ST Aladdin bulletin board"
NOTE "       2  Atari ST RT bulletin board"
NOTE
NOTE "Enter the menu number of the bulletin board."
NOTE "Press RETURN with no number to enter a BB page number."
NOTE "Press ESC at any time to abort the script."
NOTE
NOTE "       Menu Selection:"
GETSTRING 1
IF SUCCESS                         ESC not pressed
IF STRING 1 IS "1"                 ST Aladdin BB selected
 SETSTRING 1 "1000"               ST Aladdin BB page
ELSE                               Menu item 1 was not selected
 IF STRING 1 IS "2"               Atari ST BB selected
   SETSTRING 1 "475"              Atari ST BB page
 ELSE                             Menu item 1 or 2 was not selected
   NOTE
   NOTE "Enter the page number for the bulletin board to check."
   GETSTRING 1
 ENDIF
ENDIF
NOTE "Enter the date to start reading messages as YYMMDD.(Year Month Day)"
GETSTRING 2
IF SUCCESS
LOG ONTO "%1;1"
SENDLINE "REA ALL ALL CAT=1-1000 DATE>%2 NOR"
WAITFORPROMPT
LOG OFF
ENDIF
ENDSCRIPT

     Note: The indents for branch statements are not required, but it
makes it easier to see which steps belong to which branches.

     By using unconditional branches with the conditional branches,
placing one conditional branch inside another would not be necessary.
This is called nesting for those who might be interested or have heard
the term before.  Next time we will use unconditional branches to
eliminate the nesting.




CHAPTER 5
"""""""""
    [PT5]

                     >>> UNCONDITIONAL BRANCHES <<<
                     """"""""""""""""""""""""""""""

     Last time I explained using conditional branches in ST Aladdin
scripts.  Branches allow a script to handle multiple situations without
having to be rewritten for each one.

     Unconditional branches will be executed every time they are
encountered.  At first this may seem useless.  If the script should
branch to a certain place every time an unconditional branch is
encountered, why is the branch needed at all.  Why not just write the
steps in the desired sequence?  The examples below should make clear the
usefulness of unconditional branches.

     ST Aladdin scripts allow two unconditional branches, the GOTO and
CALL commands.  The CALL command might not be considered an unconditional
branch by some, but in the current discussion of branches it fits very
well.

     Both the GOTO and CALL commands direct the next script step to a
different location than the line sequence would indicate.  The GOTO
redirects the sequence permanently, that is the script will not return to
the steps following the GOTO command unless another command redirects the
sequence.  The CALL command redirects the sequence temporarily, upon
completion of the redirected sequence, the steps following the CALL
command are executed.  This is the major difference in the two commands.
The details will be discussed below.

     The GOTO command causes the script to go to the specified label.
This is useful if a certain portion of the script should be skipped for
one reason or another.  The form is:

     GOTO label

The label can be anywhere in the script.  A label is defined by a single
word preceded by a : as in:

     :label

     When the script encounters a GOTO command the next instruction
processed will be the one after the label specified in the GOTO command.
An example is:

     instruction 1
     instruction 2
     GOTO mylabel
     :anotherlabel
     instruction 3
     instruction 4
     ...
     :mylabel
     instruction 8
     ...

In this case after instruction 2 is completed, instruction 8 will be the
next instruction executed.  Instructions 3 to :mylabel will be skipped.
This may seem foolish but somewhere else in the script there would be a
GOTO anotherlabel command so those instructions would be performed then.

     The above sequence would be used if a certain series of instructions
were always to be performed, but in some cases additional instructions
needed to be performed first.  This is one reason for the unconditional
branch, to save duplication of steps.  In this case the unconditional
branch is almost always paired with a conditional branch to determine if
the condition for the additional steps was met.

      The CALL command temporarily redirects the sequence of steps to the
location of the specified label.  The CALL command label must meet the
same restrictions as the label used by the GOTO command.  There is a
significant difference in the format of the CALL command steps.  The
sequence of steps following the label called by the CALL command must end
with the RETURN command as shown below.

     CALL mylabel
     instruction 3
     instruction 4
     GOTO anotherlabel
     :mylabel
     instruction 8
     instruction 9
     RETURN

In this case, the script would reach the CALL command, perform instruc-
tions 8 and 9, then return to perform instructions 3 and 4.

     Since the CALL command temporarily redirects the sequence of events,
something must be done to prevent the script from performing the steps
which should only be performed by the CALL command.  The above example
showed a GOTO command which directed the sequence away from the CALL
command steps.  Such a redirection is always needed to prevent a script
error "RETURN without a CALL."  Generally all the CALL command steps are
grouped at the end of the script so the GOTO command will redirect the
script to the ENDSCRIPT command.

     The CALL command cannot call a label which is outside the script.
Each script is defined as the commands between the SCRIPT # and ENDSCRIPT
commands.

     The CALL command has many uses, all of which could generally be done
by a conditional branch.  The operation of the specific script determines
if the CALL command has advantages over the conditional branch or not.
The first case of advantage is if the same steps need to be performed
under different conditions.  In this case the CALL command will prevent
duplicating the steps for each condition where the steps need to be
performed.  The second case of advantage is if the same steps need to be
performed in a different sequence under different conditions.  In this
case the steps can be broken down into groups of consistent steps and the
sequence determined by the order each group is called by the CALL
commands.  This may require an example.

     IF STRING 1 IS "action 1"
       CALL block1
       CALL block2
       CALL block3
     ENDIF
     IF STRING 1 IS "action 2"
       CALL block3
       CALL block1
       CALL block2
     ENDIF

The blocks could be any set of instructions which need to be performed in
a different order depending on what action is to be performed.  An
example might be the order bulletin boards are accessed while on GEnie.

     The last advantage I will mention is one of simplicity for modifica-
tion.  If a conditional branch requires many steps be performed, it is
much easier to follow the flow of steps using a CALL command from the
conditional branch than to include all the steps in the conditional
branch.

     I won't provide an example for all the advantages of using the CALL
command, but if you are really interested, take a look at my Multiple
Scripts script in the ST Aladdin RT library.  It uses the CALL command to
allow a single script to use many other scripts.

     Before providing the promised modification to the Read Messages
script, let me provide some guidance on labels.

     Labels can be more than one word.  It can be an entire sentence if
desired and the script will not show any errors.  However, only the first
word is used to find the label.  A word is defined by the characters
between the : and the first space or carriage return.  Thus if more than a
single word is used for a label care must be used to prevent confusion
when debugging the script.  Labels are not case sensitive so :MYlable is
the same as :mylabel.  Below are some examples of labels and what would
be used by the script.

     LABEL                                        SCRIPT USE

     Go here when true                            Go

     Go here when false                           Go

     Go_here when true                            Go_here

     As you can see from the above examples.  If the first and second
examples were used in the same script the script would always go to the
first Go encountered.  This could cause some real confusion when trying
to determine why things weren't working as planned.  Be sure your labels
are unique.  The script language doesn't check to be sure each label is
unique.

     Next time we will look at the file commands available in ST Aladdin
scripts.  Some of these will allow us to have the script start and end
the capture file for us when capturing messages.

     Now for the modified Read Messages script using unconditional
branches.  By using the GOTO command we can eliminate the nested
conditional branches making the script easier to modify.  Any number of
menu options can now be easily added by simply adding more conditional
branches before the enter page number section of the script.  The
execution of the script is unchanged, but modification is greatly
simplified.

     To show how the CALL command might be used we will add the steps
necessary to display which bulletin board was selected.  This use of the
call commands doesn't save any steps but it does provide a working
example.


SCRIPT 3 Read Messages
ECHO OFF                           Don't display script commands
CLEAR                              Clear the screen
NOTE
NOTE "This script will retrieve messages from a GEnie bulletin board"
NOTE "starting at the specified date.  Messages from all categories not"
NOTE "permanently ignored will be retrieved."
NOTE
NOTE "Be sure to start a capture file before running this script."
NOTE
NOTE "       Bulletin boards available"
NOTE
NOTE "       1  ST Aladdin bulletin board"
NOTE "       2  Atari ST RT bulletin board"
NOTE
NOTE "Enter the menu number of the bulletin board."
NOTE "Press RETURN with no number to enter a BB page number."
NOTE "Press ESC at any time to abort the script."
NOTE
NOTE "       Menu Selection:"
GETSTRING 1
IF SUCCESS                         ESC not pressed
IF STRING 1 IS "1"                 ST Aladdin BB selected
  SETSTRING 1 "1000"               ST Aladdin BB page
  SETSTRING 3 "ST Aladdin"         Name of BB selected
  CALL Show_BB                     Show which BB was selected
  GOTO Enter_date                  Get the date to check
ENDIF
IF STRING 1 IS "2"                 Atari ST BB selected
  SETSTRING 1 "475"                Atari ST BB page
  SETSTRING 3 "Atari ST"           Name of BB selected
  CALL Show_BB                     Show which BB was selected
  GOTO Enter_date                  Get the date to check
ENDIF
NOTE
NOTE "Enter the page number for the bulletin board to check."
GETSTRING 1
:Enter_date                        Enter the date to check
NOTE "Enter the date to start reading messages as YYMMDD.(Year Month Day)"
GETSTRING 2
IF SUCCESS
LOG ONTO "%1;1"
SENDLINE "REA ALL ALL CAT=1-1000 DATE>%2 NOR"
WAITFORPROMPT
GOTO End                           Go to the end of the script
:Show_BB                           Show which BB was selected
  NOTE "The %3 Bulletin Board was selected."
RETURN
:End
LOG OFF
ENDIF
ENDSCRIPT




CHAPTER 6
"""""""""
    [PT6]

                         >>> FILE COMMANDS <<<
                         """""""""""""""""""""

     This week we will take a look at the commands in ST Aladdin which
deal with disk files.  There are only four commands and they are easy to
work with.

     The most frequently used file commands are the CAPTURE and
ENDCAPTURE commands.  These commands will start and end a file capture of
the on-line session.  The format is:

     CAPTURE "filename"
     ENDCAPTURE

     A file capture will copy all text displayed on the screen to the
specified file.  This allows saving information for later reference
without having to retrieve it again.  This is what happens when you do a
browse of library files.  The descriptions are saved to a file for later
display.

     The CAPTURE command accomplishes the same action as the Start Text
Capture option under the Terminal menu.  The difference is the CAPTURE
command must provide the file path and name to use, since no Item
Selector box is provided for selection as with the Start Text Capture
menu option.

     Since the CAPTURE command performs the same operation as the Start
Text Capture Terminal menu option, they cannot both be active at the same
time.  This means a CAPTURE command in a script will stop a capture
started by the Terminal menu option.  Once the capture is stopped, it will
not be resumed when the script capture is stopped.

     The ENDCAPTURE command accomplishes the same action as the End Text
Capture option under the Terminal menu.  This command will stop the
capture of on-line information and save the file to disk.

     It is important to always stop a file capture before exiting
Aladdin.  Only part of the file may be saved if the capture is not ended
before exiting.  The capture can be stopped after logging off GEnie, but
it should be ended to allow saving the entire file.  Use of the End Text
Capture option will stop a capture, that was started by a script CAPTURE
command if the ENDCAPTURE command was not used.

     The CAPTURE command will append a file to an existing file if the
same name is used.  This allows saving information in the same file for
easy reference.  It also prevents accidentally overwriting a file with a
script CAPTURE command.  If it ever seems like the CAPTURE command  didn't
work, be sure to check the end of the captured file for the information.
It may have been added to a file which already existed.

     The CAPTURE command will create a new file if the name doesn't
exist, but it will not create a new folder.  If the specified path does
not exist, the capture will not be saved, and no script error will  occur.

     ST Aladdin provides the IF SUCCESS command which should determine if
the capture was opened successfully or not.  This command was discussed
in part 4 of the scripts articles.  If the capture file was opened
successfully, the SUCCESS flag should be set to true, so the IF SUCCESS
command should show true and be executed.  If the capture file was not
opened, the SUCCESS flag should be set to false, so the IF SUCCESS
command will show false and not be executed.  This does not work properly
in version 1.23 of ST Aladdin.  The IF SUCCESS command always shows TRUE,
even if the CAPTURE command failed to open the file.

     Another file command provides a work around to check if the CAPTURE
command was able to open the specified file.  The IF EXIST command will
check if the specified file exists.  The format is:

    IF EXIST "file to check for"

it can be used just like any other IF statement in the script language.

     By using the IF EXIST command with the same path and file name as
the CAPTURE command, the script can determine if the specified file was
created.  If it exists, the capture should work, if it doesn't, it won't
work for sure.  An example is shown below:

    CAPTURE "E:\GENIE\FILE.TXT"        start capture.
    IF EXIST "E:\GENIE\FILE.TXT"       does the file exist?
       NOTE "Capture begun"            note not necessary.
    ELSE                               file doesn't exist.
       NOTE "file not opened, aborting."
       GOTO END                        abort script
    ENDIF
    ;the rest of the script
    :END                               go here to abort
    ENDSCRIPT

     The last file command is the ERASEFILE command.  This command will
erase (delete) a file from the disk.  If the specified file was found and
erased, the SUCCESS flag is set to TRUE and if not, to FALSE.  This can
be used with the IF SUCCESS command to determine if the file was erased.
An example of the ERASEFILE command is provided below:

     ERASEFILE "E:\GENIE\FILE.TXT"

If the ERASEFILE command does not find the file, no script error will
occur.

     All the commands which require specifying a file can use a string
variable for the specification.  Examples are provided below for the file
being specified in string variable 2.

    CAPTURE %2
    IF EXIST %2
    ERASEFILE %2

     That wraps up the ST Aladdin script commands dealing with disk
files.  Next time we'll take a look at some miscellaneous commands which
can add some special features to scripts.

     Now we'll use some of the commands to allow the script to open and
close the capture file in our read messages script.  We could allow
entering a file name each time the script is run, but this time we will
set a permanent file name which will be appended when new messages are
read.

SCRIPT 3 Read Messages
ECHO OFF                           Don't display script commands
CLEAR                              Clear the screen
NOTE
NOTE "This script will retrieve messages from a GEnie bulletin board"
NOTE "starting at the specified date.  Messages from all categories not"
NOTE "permanently ignored will be retrieved."
NOTE
NOTE "Messages will be saved to the file named MESSAGES.TXT in the same"
NOTE "folder as the Aladdin program."
NOTE
NOTE "       Bulletin boards available"
NOTE
NOTE "       1  ST Aladdin bulletin board"
NOTE "       2  Atari ST RT bulletin board"
NOTE
NOTE "Enter the menu number of the bulletin board."
NOTE "Press RETURN with no number to enter a BB page number."
NOTE "Press ESC at any time to abort the script."
NOTE
NOTE "       Menu Selection:"
GETSTRING 1
IF SUCCESS                         ESC not pressed
 IF STRING 1 IS "1"                ST Aladdin BB selected
  SETSTRING 1 "1000"               ST Aladdin BB page
  SETSTRING 3 "ST Aladdin"         Name of BB selected
  CALL Show_BB                     Show which BB was selected
  GOTO Enter_date                  Get the date to check
 ENDIF
 IF STRING 1 IS "2"                Atari ST BB selected
  SETSTRING 1 "475"                Atari ST BB page
  SETSTRING 3 "Atari ST"           Name of BB selected
  CALL Show_BB                     Show which BB was selected
  GOTO Enter_date                  Get the date to check
 ENDIF
 NOTE
 NOTE "Enter the page number for the bulletin board to check."
 GETSTRING 1
 :Enter_date                       Enter the date to check
 NOTE"Enter the date to start reading messages as YYMMDD.(Year Month Day)"
 GETSTRING 2
 IF SUCCESS
  LOG ONTO "%1;1"
  CAPTURE "MESSAGES.TXT"           Open capture file
  IF EXIST "MESSAGES.TXT"          The file was opened
   NOTE " "                        Move to next line
   NOTE "Capture started."         Display message
  ELSE                             File not opened
   NOTE "Capture file not opened, aborting"
   GOTO End                        abort the script
  ENDIF
 SENDLINE "REA ALL ALL CAT=1-1000 DATE>%2 NOR"
 WAITFORPROMPT
 ENDCAPTURE                        Close the capture file
 GOTO End                          Go to the end of the script
 :Show_BB                          Show which BB was selected
 NOTE "The %3 Bulletin Board was selected."
 RETURN
 :End
 LOG OFF
ENDIF
ENDSCRIPT




CHAPTER 7
"""""""""
    [PT7]


              >>> OTHER COMMANDS IN ST ALADDIN SCRIPTS <<<
              """"""""""""""""""""""""""""""""""""""""""""

     As I promised last time, this article will take a look at some
miscellaneous commands which add special features to ST Aladdin Scripts.

     The BEEP and ALARM commands allow the script to notify the user at a
particular time.  Both of these commands produce a beep from the computer
speaker (sounds like a bell to me).  The BEEP command will sound a single
beep and then the script will proceed.  This is the same sound that
occurs when you enter Basic*Services on GEnie.  The ALARM will make the
same sound as BEEP, but the beeping will continue until ESC is pressed.
An Alert box is displayed with the message Press ESC...  The script will
stop until the alarm is silenced.

    The format of the BEEP and ALARM commands are:

    BEEP
    ALARM

no other information is required.

    The GETKEY command will stop the script until a key is pressed.  The
key is stored in the specified variable as in:

    GETKEY 1

    In this case the key pressed is stored in string variable 1.  This is
a good way to retrieve a single value for menu selection.  No RETURN is
required.  This is also a good substitute for the GETKEYPRESS command
which is designed to stop the script until a key is pressed, but doesn't
work.

    The HANGUP command will immediately hangup the modem using the stored
hangup string in ST Aladdin.  It is cleaner to use the LOG OFF command
when finished with a script, but if you think the script could get stuck
and want to be sure the script disconnects the GEnie session, HANGUP will
do the same thing as turning off your modem while connected to GEnie.

    The HIDE command will prevent the transmitted characters from being
displayed on the screen.  This is what happens when your account number
and password are sent to GEnie after the U# prompt is received.  Any time
you want to send something to GEnie, you don't want the script to display
on the screen, use the HIDE command.  The hide feature must be turned ON
and OFF when done as in:

    HIDE ON
    SEND "my account number and password"
    HIDE OFF

    You can have your script check if you are already logged onto GEnie
with the ONLINE command.  It is used in an IF statement to determine if
the modem Carrier Detect (CD) line is on.  If the modem is connected the
IF ONLINE command will evaluate as true allowing the if conditions to be
executed.  The format is:

    IF ONLINE
    these commands will be executed
    ELSE
    these commands will be executed
    ENDIF

    The PAUSE command halts the script for the specified number of
seconds.  Sometimes GEnie takes some time before the next command can be
executed.  This is generally handled by the WAITFOR and WAITFORPROMPT
commands which were discussed in previous articles.  There are a few
circumstances where no prompt is provided before the next information is
needed.  In these cases the script must be able to delay for a specified
time.  The PAUSE command will provide the required delay.  The PAUSE
command works with full or fractions of seconds.  The format is:

    PAUSE 30.5

This will halt script operation for 30 and one half seconds.

    Another command which will delay script operation until a specified
time is the WAITUNTIL command.  This command will halt script operations
until the specified clock time is reached.  The time is specified in the
24 hour format so 1:00 pm is 13:00.  An example is:

    WAITUNTIL 13:00

which will halt the script until 1:00 pm.  An Alert box is displayed with
the message Waiting until 13:00, pressing ESC will abort the script.

    The WAITUNTIL command is useful for allowing a script start at a
specified time.  Since the script uses the computer clock to know when
the time is reached, the computer clock must be set correctly for proper
operation.

    The PERFORM command allows one script to run another script.  This
command can run any script except the one it is called from, including
script 1 (AutoPass 1) and script 2 (AutoPass 2).  When the script
encounters the PERFORM command, it will jump to the specified script,
accomplish its operation, excluding any LOG OFF commands, and return to
the current script.  With the PERFORM command and the WAITUNTIL command,
you could have the computer perform AutoPass 1 during the night or early
morning so it is ready for review when you get up.  A simple script looks
like this:

    SCRIPT 3 Timed AutoPass 1
    ECHO OFF                           Don't show commands
    CLEAR                              Clear the screen
    NOTE "Enter the time to perform AutoPass 1 as HH:MM."
    NOTE "Use 24 hour clock.  Insure Computer clock is correct."
    NOTE "Press ESC to abort script."
    GETSTRING 1                        Time to do AutoPass 1
    WAITUNTIL %1                       Wait for time
    PERFORM 1                          Do AutoPass 1
    LOG OFF                            log off GEnie when done
    ENDSCRIPT

    Some people are a little nervous letting the computer log onto GEnie
while they are not watching, just in case something goes wrong and the
dollars keep mounting.  Aladdin should log off when the timeout time
elapses providing a second safeguard, but you have to decide if you are
willing to try a timed script.  Personally I watch.

    The last script commands I will address are the XMODEM and ZMODEM
commands.  The XMODEM command can be used for both upload and download
operations.  ZMODEM can only be used for downloading since GEnie does not
support ZMODEM uploads.  The command formats are:

    XMODEM UPLOAD "E:\GENIE\FOLDER1\MYFILE.ARC"
    XMODEM DOWNLOAD "E:\GENIE\FOLDER1\MYFILE.ARC"
    ZMODEM
    ZMODEM "E:\GENIE\FOLDER1\"

    The XMODEM direction must be specified since both uploads and
downloads are possible.  Since XMODEM does not pass a file name one must
be specified for each file.  ZMODEM will pass the file name, so only a
path is needed.  If no path is specified for either XMODEM or ZMODEM the
files will be placed in the same folder as the Aladdin program.

    ZMODEM is automatic with ST Aladdin, so the ZMODEM command without a
path is not required.  When Aladdin recognizes a ZMODEM download has
started, it will automatically begin the ZMODEM capture.  If a path was
specified with the ZMODEM command, the files will be placed into the
specified path, if no ZMODEM command was used or no path specified, the
files will be placed in the same folder as the Aladdin program.

    This ends the Intro to Scripts series.  St Aladdin has more script
commands than this series has mentioned, so be sure to check the manual
if you want to do something that wasn't covered.




CHAPTER 8
"""""""""
    [PT8]


                 >>> INTRO TO SCRIPTS, INTERRUPTED <<<
                 """""""""""""""""""""""""""""""""""""
                        (Too good to believe? :-)

NOTE: The following article was my idea of the perfect script language.
""""  The article was reprinted in the April Fools issue of GEnie Lamp
on April 1st 1991.

     I am going to interrupt my normal sequence of articles on writing
scripts for ST Aladdin 1.2 for some great news for script writers and
users.  The next article will continue with the current script
capabilities of ST Aladdin.

     Since I have been experimenting with ST Aladdin scripts and writing
more than a few scripts, Gordon and Tim were gracious enough to allow me
to take a look at what scripts will look like in the future ST Aladdin. I
hesitate to provide this look since it may discourage people from writing
scripts for ST Aladdin 1.2 but decided this was just too good to pass up.

     First let me tell you this will not be available in the near future.
Lots of smaller changes to be worked on in ST Aladdin before the time can
be expended to fully debug this new script language, but it will knock
your socks off when you get it!  (Please don't bug Gordon and Tim about
this.  They didn't want me to say anything, you know, something about not
releasing features until they are ready to be distributed, and all that
stuff.  But, being the person I am, I just couldn't pass this up.
Please, Gordon and Tim, don't hold this against me.  I promise next time I
won't tell a soul.)

     This new and improved script language is designed with the user in
mind.  Not only does it not take programming experience to use, it is so
easy to use, if you can log onto GEnie with ST Aladdin, you can create
your own custom script.  Sound hard to believe, just wait.

     There are over two hundred fifty commands which the new script
language understands.  This may sound a little daunting at first, but it
is no problem, mainly because you don't have to remember them to write a
script.  In fact, you might not ever have to type a single script command.
That's right, you can create an entire script without typing a single
script command.

     I know what you are thinking, here is another auto script program
which will record what I manually do and then play it back.  Well, you are
partially right.  Scripter (my name, the official one remains to be
released) will record all your online actions and play them back at a
later time, but it can do much more.

     When Scripter is run from the ST Aladdin terminal menu there are two
choices, RECORD user script or PLAY user script.  If no scripts are
available RECORD is the only option selectable, PLAY is grayed out.

     GEnie will have a new file available for use with Scripter.  In that
file are all the menu screens available on GEnie.  The version I got to
see only had the thirty most popular pages, but it was enough to see how
things will work.

     Let's take a look at what a typical recording session with Scripter
will be like.  When RECORD is selected Scripter looks for the menu file.
If the file is not found you have the option to log onto GEnie or abort
the recording session.  If log onto GEnie is selected, an item selector is
presented to enter the script name and Aladdin logs onto GEnie using your
user ID and password.  Scripter stops at the GEnie opening screen where
you can manually navigate through the desired actions.  At any time you
can select stop and Scripter will stop recording your actions and save
the script file.  The script will automatically stop when you log off
GEnie during the recording session.  The script can be played to
accomplish the exact actions you just recorded.  If you want to make
different choices during script playback, you need to modify the script
placing variables where the desired choices were made.

     The really nice features of Scripter show up when the GEnie menu file
is available.  If the menu is available when RECORD is selected things
seem to proceed as before but there are a few major changes. Instead of
logging onto GEnie, the menu screens are presented off line. All the menu
choices can be selected, but of course no data is shown. All desired
selections can be recorded for execution during script playback.  This is
the same as manual recording, but you are off line, so no charges are
accumulating the entire time you are creating the script.  The real
advantage comes when you reach a menu choice or entry request which you
wish to set-up as a variable.  Instead of having to go back and modify the
recorded script, just press the ? and a variable will be assigned to that
selection.  If you want to specify some text to be displayed when the
variable value is requested, all you need do is press ALT T.  A dialog box
appears where up to three lines of 75  characters each can be entered.
Again the script can be stopped at any time by selecting STOP or pressing
ALT S.  It is automatically stopped when LOG OFF is selected.

     After a session is recorded it can be played back whenever you want
to accomplish the script actions.  If the script has no variables it will
proceed from start to finish with no interaction required.  If a capture
was used during the original recording, the same file name will be used
and the information appended if the file already exists.  If any variables
were used in the script, the script will display the menu selection line
or the entered text requesting the variable value.  Once all variable
values have been entered, the script will log onto GEnie and accomplish
all actions.

     As if this isn't enough, there is more.  Any script can call any
other script.  This means if during a recording session, you decide you
want to perform a previously recorded script, it can be done.  While
recording, just press the ALT I key to include another script.  An item
selector will be displayed to select the desired script.  There are some
precautions here.  The script being recorded must be at a prompt where the
included script can legally start and the included script must end at a
place where the new script can begin again.  This is not a problem if the
included script was recorded all the way through log off since start and
stop occur at a page menu.

     Including scripts works with either Scripter mode, that is, with
manual recording or with the GEnie menu file.  The difference is if you
are in the manual record mode, the included script will be executed
immediately, where in the menu record mode, the script will just be
inserted in the proper place, and only played when the recorded script is
played.  If the inserted script ended with a LOG OFF, it will not log off
GEnie, just return to the recorded script.  The one hazard to inserting
scripts in the GEnie menu mode is you don't know where the inserted
script will end.  If it was stopped before the LOG OFF command, it may not
be at a page menu, which could cause problems.  I have suggested the
inserted script display the final menu item where it stops to prevent any
confusion when using the GEnie menu mode.

     One of the nice features of the insert script command is it allows
creating custom script sequences.  Select RECORD user script and then just
start inserting the desired scripts.  When all scripts have been inserted,
select LOG OFF and the script is ready to go.  With this feature you can
even use the same script multiple times allowing you to essentially create
your own AutoPass 1 script.

     If it weren't for the intelligent way Scripter uses variables
multiple scripts could cause a serious conflict.  Since Scripter assigns
variables as they are encountered in the script, multiple scripts are no
problem.  As the script is executed, each variable is assigned a
sequential number which will be used to match the value with the proper
script location.  It is even possible to have the same value entered
multiple places in the script.  This is accomplished by pressing ALT D.
This displays a list of variables already used in the script, from which
one may be selected to fill the required place.  There is even a
capability to select any of the configuration variables, such as user ID
or BB page number, as well as set up a table of default values to use for
variables.  Scripter has the most flexible use of variables in any script
language I have seen.

     Scripter has a built in time feature which will allow starting a
script at a specified time or with a specified delay.  When a script is
placed into a delayed start, you are returned to ST Aladdin to perform
other operations.  As long as you don't leave ST Aladdin the script will
be performed when the time arrives.  The only precaution is to not be
doing one script or manual action on GEnie when the time for the script
arrives, because it will begin when it should.  A feature which asks if
the timed script should start, wait until you are finished, or abort would
be nice.  Perhaps this will be added to the final version, after all this
is only a beginning, but what a beginning.

     You will notice I haven't mentioned anything about keyboard commands.
All scripts can be written without knowing about the syntax of the
language, sequence of events required, string handling or any of those
things.  If you are really determined to make script writing hard, you can
do all script writing manually with the 250 plus commands.  I don't know
why you would want to do this, but the capability is still there. Oh by
the way, did I mention the number of scripts is limited only by disk
space.  Since each script is assigned its own file name, and loaded from
an item selector, you can place scripts anywhere you choose and have as
many as your disk will hold.  And for floppy drive users, scripts can be
stored any where the item selector can find them, which includes floppy
disks.  The only problem with floppy drives is if the disk isn't in place
when the script is run, things will come to a screeching halt.

     There might be other features added before the general public sees
Scripter, although I can't imagine what.  Voice recognition?  For those
who have been waiting to write their own scripts once Scripter is released
you will have to wait no longer.  This has to be the easiest script writer
I have ever seen.  The only thing which could be easier would be to have
someone else know exactly what you wanted and do it for you, but then what
personal satisfaction could be gained from that?

     Now if I could only get ............... ring ring ring ring.  What?
What time is it?  4:00?  This can't be a dream! :-)




Chapter 9
"""""""""
    [PT9]


                 >>> SUMMARY OF COMMANDS MENTIONED <<<
                 """""""""""""""""""""""""""""""""""""
                 ~ ST Aladdin V 1.2a Script Commands ~

     This is not a complete list of ST Aladdin script commands.  It is a
summary of the commands mentioned in the above articles.  Look at the
above examples or scripts on GEnie for specific application.


ALARM          Sounds a beep sound and displays an Alert Box message
               Press ESC...

               Format:   ALARM

               Script will stop and beeping will continue until ESC is
               pressed.

BEEP           Sounds a single beep sound then script continues

               Format:   BEEP

               This is the same sound that occurs when you enter
               Basic*Services on GEnie.  ALARM and BEEP make the same
               sound.

CALL           Temporarily redirects the sequence of steps to the location
               of the specified label.

               Format:   CALL label

               The sequence of steps following the label called by the
               CALL command must end with the RETURN command as shown
               below.

               CALL mylabel
               ...

               :mylabel
               ...

               RETURN

CAPTURE        Starts capturing all text displayed on the screen to the
               specified file.

               Format:   CAPTURE "filename"

               This accomplishes the same thing as the Start Capture
               selection under the dropdown menu.

CLEAR          Clears the terminal screen.

               Format:   CLEAR

               This command just clears the computer screen and has no
               effect on the connection to GEnie.

CURRENTLINEHAS Determines if the current line being received contains the
               specified string.  Used with IF command.

               Format:   IF CURRENTLINE HAS "string"
                         ...

                         ELSE
                         ...

                         ENDIF

               The current line is ended by a carriage return.
               The comparison is case sensitive, like the other string
               comparisons so the string match must be exact.

delimiters     Mark the beginning and end of string variarbles.

               Format:   "string to mark"

               Any of the following may be used as delimiters:

               ( )  [ ]  { }  < >  ` '  " "

               Only the delimiters may not appear in the string.

ECHO           Determines if commands will be displayed on the screen or
               not.

               Format:   ECHO state

               Where:    state is ON to display commands
                                  OFF to hide commands

               The default state is ON so commands will be displayed if
               no ECHO command is included in the script.  The NOTE
               command is never shown, only the string it is to display.

ELSE           Defines the steps to be performed when the IF portion of a
               conditional branch is not true.

               Format:   IF
                         ...

                         ELSE
                         ...

                         ENDIF

               ELSE is always optional in the IF conditional branch.

ENDCAPTURE     Stops the capture of text displayed on the screen.

               Format:   ENDCAPTURE

               This command accomplishes the same thing as Stop Text
               Capture under the dropdown menus and will end a capture
               started with CAPTURE command or the Start Text Capture
               dropdown menu selection.

ENDIF          Defines the end of the IF conditional branch.

               Format:   IF    or  IF
                         ...       ...

                         ELSE      ENDIF
                         ...

                         ENDIF

               ENDIF is always required to terminate an IF statement.

ENDSCRIPT      Indicates the end of the current script.

               Format:   ENDSCRIPT

               This command MUST be the last command in all scripts.

ERASEFILE      This command will erase (delete) a file from disk.

               Format:   ERASEFILE "E:\FOLDER\FILE.TXT"

               If the specified file is found and erased, the SUCCESS
               flag is set to TRUE and if not, to FALSE.  This can be
               used with the IF SUCCESS command to determine if the file
               was erased.

               If the ERASEFILE command does not find the file, no script
               error will occur.

EXIST          This command will check if a file exists.

               Format:   IF EXIST "E:\FOLDER\FILE.TXT"

               If the specified file exists the next steps are executed
               just like any other IF statement in the script language.

GETKEY         Stops the script until a key is pressed.

               Format:   GETKEY number

               Where:    number is the string variable number 0 to 9.

               The key pressed is stored in the specified variable.
               No RETURN key press is required.

GETSTRING      Allows entering the value of a string variable from the
               keyboard.

               Format:   GETSTRING number

               Where:    number is the string variable number 0 to 9

               The entered string can be any characters including spaces.
               The string can have 75 characters maximum and is terminated
               by a carriage return.

GOTO           Causes the script to go to the specified label and not
               return.

               Format:   GOTO label

               The label can be anywhere in the script.

               When the script encounters a GOTO command the next
               instruction processed will be the one after the label
               specified in the GOTO command.

HANGUP         The HANGUP command will immediately hangup the modem using
               the stored hangup string in ST Aladdin.

               Format:   HANGUP

               HANGUP will do the same thing as turning off your modem
               while connected to GEnie.

               It is cleaner to use the LOG OFF command.

HIDE           The HIDE command will prevent the transmitted characters
               from being displayed on the screen.

               Format:   HIDE state

               Where:    state is ON    to hide characters
                                  OFF   to show characters

               Default is HIDE OFF.

               Any time you want to send something to GEnie, you don't
               want to display on the screen use the HIDE command.

IF             Defines the beginning of the IF conditional branch.

               Format:   IF    or  IF
                         ...       ...

                         ELSE      ENDIF
                         ...

                         ENDIF

               IF is always required to start an IF statement.

               ELSE is optional for all IF statements.

label          A lable is defined by a single word preceded by a :

               Format:   :label

               A label is not case sensitive, ie. LABEL is the same as
               label.  A label definition stops at the first space.

LOG OFF        Terminates the GEnie on-line session in an orderly
               fashion.

               Format:   LOG OFF

               Will terminate the session using the GEnie BYE command.
               If STAY is selected on the ST Aladdin menu, the LOG OFF
               command will be ignored.  LOG OFF allows any automatic
               settings such as check mail to be accomplished before the
               session is terminated.

LOG ON         Logs onto GEnie stopping at the opening page prompt.

               Format:   LOG ON

               Most times the script needs to be a particular page to
               accomplish its task, it saves time to use the LOG ONTO
               command instead.

LOG ONTO       Enters GEnie at the specified page and menu option.

               Format:   LOG ONTO "page;option"

               Where: page is the desired page number
                      option is the desired menu option

               This will send the page;option command after successful log
               onto GEnie using the ST Aladdin log on configuration.

NOTE           Sends the specified characters to the screen.

               Format:   NOTE "string"

                          or

                         NOTE "%2"

               The string can be any characters including spaces.
               This information is only sent to the screen and not to
               GEnie if logged on at the time.
               A string variable may be used as shown above.

ONLINE         Checks if logged onto GEnie.

               Format:   IF ONLINE
                         ...

                         ELSE
                         ...

                         ENDIF

               Determines if the modem Carrier Detect (CD) line is on.

PAUSE          Halts the script for the specified number of seconds.

               Format:   PAUSE seconds

               Where:    seconds is the number of seconds to delay

               The PAUSE command works with full or fractions of seconds.

PERFORM        Runs one script from another.

               Format:   PERFORM number

               Where:    number is the script to run 1 to 9.

               This command can run any script except the one it is
               called from, including 1 (AutoPass 1) and 2 (AutoPass 2).
               All commands in the called script will be performed except
               the LOG OFF Command.

RETURN         Ends the steps to be executed by the CALL command.

               Format:   :mylabel
                         ...

                         RETURN

SCRIPT         Indicates the beginning of a script.

               Format:   SCRIPT digit text

               Where digit the script number, 3 to 9.
                     text is the name of the script to be displayed in the
                     script menu. (20 characters max.)

SEND           Sends the specified character(s) with no carriage return.

               Format:   SEND "string"

                          or

                         SEND "%1"

               Where:    string is one or more characters including
                         spaces or a string variable as above.

SENDLINE       Send the specified string with a carriage return.

               Format:   SENDLINE "string"

                            or

                         SENDLINE "%1"

               The string can be any combination of characters
               including spaces.  A string variable can also be
               used as shown above.

SETSTRING      Assigns a string of characters to a string variable.

               Format:   SETSTRING number "string"

               Where:    number is the string variable number 0 to 9.

                         string is any characters including spaces
                         75 characters maximum.

               This allows setting the characters which a string
               variable will represent.

STRING         Condition which compares a variable with characters.

               Format:   IF STRING digit verb string
                         ...

                         ELSE
                         ...

                         ENDIF

               where:    digit is 0 to 9 representing the ten possible
                         script variables.

                         verb is either IS or HAS.

                         IS  requires the variable match exactly,
                             including upper/lower case.

                         HAS requires the variable contain the specified
                             string.

                         string is the characters to match enclosed by
                         string delimiters.

                         (delimiters show where a string starts and
                         stops, ie. " ")

SUCCESS        Used in two forms:

               IF SUCCESS determines if the previous action was successful
               or not.

               Format:   IF SUCCESS
                         ...

                         ELSE
                         ...

                         ENDIF

               If the instruction executed right before the IF SUCCESS
               branch was successful (true), the branch will be taken,
               if it was unsuccessful (false), it will be skipped.

               The success conditions which may be checked are:

               CAPTURE        - was the capture started?
               ENDCAPTURE     - was the capture ended?
               ERASEFILE      - was the file erased?
               GETSTRING      - was a string entered?
               LOG ON         - was log on successful?
               LOG ONTO       - was the log onto successful?
               SNAPSHOT       - was the screen snapshot accomplished?
               WAITFOR        - was the specified string received?
               WAITFORPROMPT  - was the prompt received?
               WAITUNTIL      - was the specified time reached?
               XMODEM         - was the XMODEM operation completed?


               SUCCESS sets the condition of the success flag checked by
               the IF SUCCESS command.

               Format:   SUCCESS TRUE

                              or

                         SUCCESS FALSE

WAITFOR        Script will not proceed until the specified string
               is received.

               Format:   WAITFOR "string"

               String is case sensitive and can be any combination of
               characters including spaces.  An exact match is required.

WAITFORPROMPT  The script will not proceed until the defined prompt is
               received.

               Format:   WAITFORPROMPT

               The ST Aladdin prompt and the GEnie prompt must be set to
               the same for this command to work.  It not only waits for
               the prompt, but also waits for no data to be sent.  Most
               fool proof way to send commands at the proper time.

WAITUNTIL      Halts a script until the specified clock time is reached.

               Format:   WAITUNTIL 13:00

               The 24 hour clock is used so the above example would halt
               the script until 1:00 pm.

               An alert box is displayed with the message Waiting until
               13:00.

               Pressing ESC will abort the script.

XMODEM         Downloads or Uploads a file using xmodem protocol.

               Format:   XMODEM UPLOAD "E:\GENIE\FOLDER1\MYFILE.ARC"

                           or

                         XMODEM DOWNLOAD "E:\GENIE\FOLDER1\MYFILE.ARC"

               Direction of transfer must be specified with xmodem.

               A filename must be specified since xmodem protocol does
               not provide one during the download.

               If no path is specified the files will be placed in the
               same folder as the Aladdin program.

ZMODEM         Downloads one or more files using zmodem protocol.

               Format:   ZMODEM

                           or

                         ZMODEM "E:\GENIE\FOLDER1\"

               ZMODEM can only be used for downloading since GEnie does
               not support ZMODEM uploads.

               ZMODEM will pass the file name, so only a path is needed.

               If no path is specified the files will be placed in the
               same folder as the Aladdin program.

               ZMODEM is automatic with ST Aladdin, so the ZMODEM command
               without a path is not required.

               Note the ending \ in the path since no filename is needed.




CHAPTER 10
""""""""""
    [PT10]


           >>> ST Aladdin V 1.2A Index of Script Commands <<<
           """"""""""""""""""""""""""""""""""""""""""""""""""

Command             Format                                  Page

ALARM               ALARM                                   78
BEEP                BEEP                                    78
CALL                CALL label                              69
CAPTURE             CAPTURE "string"                        81
CLEAR               CLEAR                                   78
COMMANDMODE         COMMANDMODE state                       84
Comment             ;text                                   67
Control characters  ^                                       67
CURRENTLINEHAS      IF CURRENTLINEHAS "string"              73
DATAWAITING         IF DATAWAITING                          75
DAYOFWEEK           IF DAYOFWEEK day                        76
Delimiters          () [] {} <> `' ""                       67
ECHO                ECHO state                              77
ELSE                ELSE                                    71
ENDCAPTURE          ENDCAPTURE                              81
ENDIF               ENDIF                                   71
ENDSCRIPT           ENDSCRIPT                               68
ERASEFILE           ERASEFILE "string"                      80
EXIST               IF EXIST "string"                       75
GETKEY              GETKEY digit                            88
GETSTRING           GETSTRING digit                         89
GOTO                GOTO label                              68
HANGUP              HANGUP                                  85
HIDE                HIDE state                              78
IF                  IF condition                            71
KEYWAITING          IF KEYWAITING                           75
KEYWAITING          KEYWAITING state                        88
Label               :labelname                              68
LOG OFF             LOG OFF                                 83
LOG ON              LOG ON                                  83
LOG ONTO            LOG ONTO "string"                       83
MAILFOUND           IF MAILFOUND                            76
MONITOR             MONITOR                                 79
NOTE                NOTE "string"                           78
ONLINE              IF ONLINE                               73
PAUSE               PAUSE seconds                           79
PERFORM             PERFORM digit                           70
QUOTES              QUOTES state                            84
RETURN              RETURN                                  69
SCRIPT              SCRIPT digit text                       67
SEND                SEND "string"                           85
SENDCOMMAND         SENDCOMMAND "string"                    85
SENDLINE            SENDLINE "string"                       85
SENDSPECIALCOMMAND  SENDSPECIALCOMMAND "string" "prompt"    86
SETSTRING           SETSTRING digit "string"
SNAPSHOT            SNAPSHOT "string"                       82
STRING              IF STRING digit verb "string"           73
SUCCESS             IF SUCCESS                              72
SUCCESS             SUCCESS condition                       77
Variables           %digit                                  67
WAITFOR             WAITFOR "string"                        86
WAITFORDATA         WAITFORDATA keyword                     87
WAITFORKEYPRESS     WAITFORKEYPRESS                         88
WAITFORPROMPT       WAITFORPROMPT                           87
WAITUNTIL           WAITUNTIL HH:MM                         80
XMODEM              XMODEM direction "string"               82
ZMODEM              ZMODEM "string"                         82


                                [*][*][*]

     Published online by:

                          T/TalkNET OnLine Publishing Co.
                          ATTEN: John Peters
                          5102 Galley Rd. 115/B
                          Colorado Springs, CO. 80915


\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\////////////////////////////////////
 To sign up for GEnie service, call (with modem) 1-800-638-8369.   Upon
 connection type HHH.  Wait for the  U#=  prompt.  Type: XJM11877,GEnie
 and hit RETURN.  The system will then prompt you for your information.
////////////////////////////////////\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
[EOF]